#ifndef PHRASECOLLECTION_H
#define PHRASECOLLECTION_H

#include "phrase.h"
#include <QList>
#include <QTextStream>
#include <QDomNode>

class Phrase;
class Lesson;

/**
 * Back-end. Core functionality. Inherits from QList<Phrase>.
 *
 * A collection of Phrase objects stored in a common QList.
 * Therefore the memory locations may not be stable. i.e. it
 * may not be safe to use pointers to the elements in memory.
 *
 * It does however provide all the convenience of a QList,
 * including both STL-style iterators.
 * <b>Examples</b>
 * <pre>
 * foreach (Phrase p, phraseCollection) { ... }
 * QList<Phrase> phrases(phraseCollection);
 * ...
 * QListIterator phraseIt(phraseCollection);
 * while (phraseIt.hasNext()) {phraseIt.next().... }
 * </pre>
 *
 * Can be initialised from an XML file or an XML directory.
 */
class PhraseCollection : public QList<Phrase>
{
    public:
        // CONSTRUCTORS ////////////////////////////////
        PhraseCollection();
        /**
         * Construct Phrase Collection from file or directory
         * @param QString filename The XML file or directory (trailing slash required!)
         * containing XML files, all of which will be recursively read.
         */
	PhraseCollection(const QString& filename);
        /**
         * Conversion constructor, from equivelant QList representation.
         */
        PhraseCollection(const QList<Phrase>& other);
        // XML INTERFACE
        /**
         * Write all the phrases contained within this PhraseCollection
         * to a new XML file, thereby achieving persistance. See project
         * documentation for a description of the XML format.
         * @param QString filename The name of the output file. Will
         * be created if does not exist. Will be overwritten if does exist.
         */
        void toXML(QString filename) const;
        /**
         * Write all the phrases contained within this PhraseCollection
         * to a new XML file, thereby achieving persistance. See project
         * documentation for a description of the XML format.
         * @param QTextStream& stream The output data stream used to write
         * output the XML.
         */
        void toXML(QTextStream& stream) const;
	
        /**
         * Transform the collection to a DOM tree with 'node' as its root.
         * See the project documentation for a description of the XML
         * file format.
         * @param QDomNode node The XML DOM node to which all the phrases
         * in this collection will be added as children.
         * @return dome node
         */
        QDomNode toXML(QDomNode node) const;

        /**
         *load the phrase collection from an XML file
         * or XML directory.
         * NOTE: directory must have trailing slash
         * NOTE: THE PHRASES READ MUST BE DELETED
         * @param QString The XML filename or directoy (must have trailing slash!)
         * which will be recursively read.
         * @param QString category The name of the Lesson object to which
         * this Phrase belongs. This allows Phrase's to be doubly-linked
         * back to Lesson's, allowing for more flexible navigation, especially
         * sequence control can remove Phrase's from their 'parent' lessons.
         */
        void fromXML(QString filename, QString category = "No category set");

        /**
         * Explicit conversion to/from QList<Phrase>
         */
        PhraseCollection& operator= (const QList<Phrase>& other);
};

#endif // PHRASECOLLECTION_H
